Skip to content

refactor: replace BaseHTTPMiddleware with pure ASGI - #475

Open
lentzvitoria wants to merge 2 commits into
SAP:mainfrom
lentzvitoria:refactor/starlette-pure-asgi-middleware
Open

lentzvitoria wants to merge 2 commits into
SAP:mainfrom
lentzvitoria:refactor/starlette-pure-asgi-middleware

Conversation

@lentzvitoria

Copy link
Copy Markdown
Contributor

Removes the dependency on BaseHTTPMiddleware in StarletteContextMiddleware, implementing it as a pure ASGI callable instead. This avoids the double-wrapping issue in Starlette that breaks streaming responses and SSE.

Disclaimer: Do not include SAP-internal or customer-specific information in this PR (e.g. internal system URLs, customer names, tenant IDs, or confidential configurations). This is a public repository.

Description

Replaces BaseHTTPMiddleware with a pure ASGI callable in StarletteContextMiddleware. Removes unused imports (Request, Response) — only Headers from starlette.datastructures is needed. Non-HTTP scopes (lifespan, websocket) are forwarded without modification.

This is not a breaking change because:

  • Constructor signature is identical: __init__(self, app, providers) — no change
  • app.add_middleware() call site is unaffected: Starlette forwards kwargs the same way for both BaseHTTPMiddleware subclasses and pure ASGI classes
  • StarletteContextMiddleware is not exported from any __init__.py — only used internally via adapters/_starlette.py
  • No test couples to BaseHTTPMiddleware-specific behavior (dispatch, Request, Response)

Related Issue

Closes #<issue_number>

(Link to the GitHub issue this PR addresses)

Type of Change

Please check the relevant option:

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update
  • Code refactoring
  • Dependency update

How to Test

  1. Add StarletteContextMiddleware to a FastAPI app via app.add_middleware(StarletteContextMiddleware, providers=[...])
  2. Make a request and confirm the SDK runtime context is populated (e.g. via get_context())
  3. Make a streaming/SSE request through the middleware and confirm it is not truncated
  4. Expected result: context populated correctly, streaming works end-to-end

Checklist

Before submitting your PR, please review and check the following:

  • I have read the Contributing Guidelines
  • I have verified that my changes solve the issue
  • I have added/updated automated tests to cover my changes
  • All tests pass locally
  • I have verified that my code follows the Code Guidelines
  • I have updated documentation (if applicable)
  • I have added type hints for all public APIs
  • My code does not contain sensitive information (credentials, tokens, etc.)
  • I have followed Conventional Commits for commit messages
  • [] (New modules only) I have attached e2e evidence showing the module working against a real BTP service
  • [] (Security-sensitive changes only) I have run /security-review and addressed all ❌ findings

Breaking Changes

N/A — this refactor does not introduce any breaking changes. See the "This is not a breaking change" section above.

Additional Notes

BaseHTTPMiddleware in Starlette has a known double-wrapping issue that breaks streaming responses and SSE (Server-Sent Events). Pure ASGI middleware avoids this entirely. See: https://www.starlette.io/middleware/#basehttpmiddleware

…mentation

Removes the dependency on BaseHTTPMiddleware in StarletteContextMiddleware,
implementing it as a pure ASGI callable instead. This avoids the double-wrapping
issue in Starlette that breaks streaming responses and SSE.
@lentzvitoria
lentzvitoria requested a review from a team as a code owner November 16, 2026 13:57

@lentzvitoria lentzvitoria left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR Review: #475: refactor: replace BaseHTTPMiddleware with pure ASGI

Author: lentzvitoria Branch: refactor/starlette-pure-asgi-middleware → main
Verdict: ⚠️ Needs Minor Work
Summary: Clean, correct refactor — one ⚠️ on the PR title scope and one ⚠️ on missing test coverage for the new __call__ path.


A: Process & Compliance

# Criterion Status Finding
A1 PR template complete ⚠️ Closes #<issue_number> is a placeholder — replace with a real issue or remove the line
A2 Conventional Commits ⚠️ PR title is refactor: replace BaseHTTPMiddleware with pure ASGI — missing scope. Should be refactor(middleware): ... to match the commit message on the branch
A3 Issue linked ⚠️ No issue linked (placeholder not replaced)
A4 AI-generated code disclosure ➖ N/A — change is small and clearly human-authored

B: Security & Sensitive Data

# Criterion Status Finding
B1 No sensitive data in code ✅ Clean
B2 No sensitive data in PR body ✅ Clean

C: Code Quality

# Criterion Status Finding
C1 CI checks passing ⚠️ All jobs pass except SDK review label present (❌ fail) — expected, no sdk-review label applied yet
C2 Version bump ➖ N/A — no version change
C3 Type hints ✅ __call__ fully annotated: scope: dict, receive: Callable, send: Callable, return None
C4 No hardcoded values ✅ "http" string is the ASGI spec literal, not a magic value
C5 Import organization ✅ Callable added to stdlib typing imports correctly
C6 Naming conventions ✅ No new names introduced
C7 No unused code ✅ Removed Request, Response, BaseHTTPMiddleware — no dead imports remain
C8 No unjustified new dependencies ✅ starlette.datastructures.Headers is already in the starlette optional dep
C9 Proto code freshness ➖ N/A

D: API & Design

# Criterion Status Finding
D1 API future-proofing ✅ Constructor unchanged
D2 Public API hygiene ✅ Class not exported publicly — internal only
D3 Breaking changes marked ✅ PR body explicitly documents why this is non-breaking
D4 Pagination & tenant filtering ➖ N/A
D5 Telemetry instrumentation ➖ N/A
D6 Multi-tenancy support ➖ N/A

E: Tests & Documentation

# Criterion Status Finding
E1 Tests added/updated ⚠️ No test exercises the new __call__ path directly — specifically the non-HTTP scope forwarding (scope["type"] != "http") is untested. Existing tests cover the HTTP path via TestClient but the websocket/lifespan passthrough has no coverage
E2 Documentation quality ✅ Docstring updated to reflect pure ASGI nature and non-HTTP scope forwarding
E2a Multi-tenancy documentation ➖ N/A — no user-guide.md changed
E3 Module structure compliance ➖ N/A — no new module

⚠️ Non-Blocking Suggestions

  • [A1/A3]: Replace Closes #<issue_number> with a real issue number or remove the line — the placeholder reads as an oversight
  • [A2]: PR title missing scope — update to refactor(middleware): replace BaseHTTPMiddleware with pure ASGI to match the commit message
  • [E1]: Add a test for the non-HTTP scope passthrough, e.g. a WebSocket or lifespan scope that verifies the middleware forwards without touching the context — small addition, but it documents the behavior and catches regressions

✅ Things Done Well

  • Correct pure ASGI pattern: __call__(scope, receive, send) with scope-type guard
  • Headers(scope=scope) is the right zero-copy way to read headers in pure ASGI — avoids materializing the full request
  • Docstring clearly explains the behavioral change and compatibility
  • self.app stored directly — no unnecessary wrapping
  • CI is green on all substantive checks (quality, tests, build, CodeQL, CLA)

Comment on lines +50 to +56
async def __call__(self, scope: dict, receive: Callable, send: Callable) -> None:
if scope["type"] != "http":
await self.app(scope, receive, send)
return

headers = Headers(raw=scope["headers"])
envelope = RequestEnvelope(headers=dict(headers))

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be possible to use a Starlette type instead of a dictionary for scope?

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants